home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 7 / Apprentice-Release7.iso / Source Code / PowerPlant / Multi-Panel Dialogs 1.1 / READ ME
Encoding:
Text File  |  1996-11-14  |  6.7 KB  |  119 lines  |  [TEXT/ttxt]
  1.  
  2.  
  3.  
  4.  
  5. What?
  6. One of the most common interfaces for preferences dialogs these days is some sort of multiple panel interface.
  7.  
  8. These classes allow you to implement such a dialog. The framework handles the switching of panels and the retrieving and inputing of data from and to each panel. It also handles reverting data in each panel and allows you to specify defaults which the user can recall. In addition, the classes are flexible enough to implement just about any type of interface you'd like in your app.
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30. How to Use: (The abridged version)
  31. The provided sample application implements a simple preferences dialog (but there's no reason this couldn't be used in other ways). This app is a good starting point where you can get and an example of how to use the classes in a real app. There's really only three steps to getting up and running with the framework.
  32.  
  33. First, you need to create subclasses of the CMPDPanel class. This class defines interface which the rest of the framework expects to see from the panels loaded in and out of the dialog. In your subclass, you can use any of the PowerPlant pane/view classes you wish to define your interface. There is one of these subclasses for each panel in your interface. Exzmples of one of these classes are the CCommunicationsPanel, CDefensePanel and CPowerPanel.
  34.  
  35. Second, you will need to create a subclass of UMPDialogHandler which will provide the actual data to the framework for each panel as it is needed. An example of this is the UTestPrefsDialogHandler.
  36.  
  37. Finally, you need to create a 'MPD#' resource in one of your resource files. You can think of this as similar to the 'Mcmd' resource in the base PowerPlant. This resource describes the the framework the number, order, resource id's and auxiliary data of the panels in the interface. There is a Resourcerer 'TMPL' for it in the MPDialog.rsrc file.
  38.  
  39. Also included in this release are two variations on the tabbed dialog-type interface. The first is based on the LAGA classes and the other is based on the Gray Council AGA classes. If you want to try out either of these optinos, you will need to download the LAGA and GrayCouncil classes from the Metrowerks PP Archive where you got this package. You will also need to #define USE_AGA_CLASSES to enable those features. In addition, you'll need to add the two MPD files which implement the tabbed interface (CMPDAGAIndexTab.cp and CMPDGrayCouncilTabs.cp).
  40.  
  41. The different resource files in the MPD Sources folder are examples of layouts you can have using the different types of interfaces.
  42.  
  43. One last note: drop the MPDialogs Custom Types.rsrc file into your Constructor folder so the CPPb's in the file for the MPD custom panes will be available in all your Constructor files.
  44.  
  45. Quick Tour:
  46. CMPDIncludeView.cp
  47. CMPDIncludeView.h
  48. The view which manages loading and unloading the different panels and the communication of the dialog handler with each panel for getting and setting the panel data.
  49.  
  50. CMPDAGAIndexTab.cp
  51. CMPDAGAIndexTab.h
  52. The subclass of LAGAIndexTab which interfaces it into the MPD framework. Uses the CMPDPanelSelectControl as a mixin.
  53.  
  54. CMPDGrayCouncilTabs.cp
  55. CMPDGrayCouncilTabs.h
  56. The subclasses of AGATabPanelPPX which interfaces it into the MPD framework. Uses the CMPDPanelSelectControl as a mixin.
  57.  
  58. CMPDPanel.h
  59. The abstract class which defines the interface for each panel in the dialog. See CCommunicationsPanel, CDefensePanel, and CPowerPanel for concrete examples.
  60.  
  61. CMPDPanelSelectControl.h
  62. Defines the interface for the mixin class which implements the communications between the control and the framework.
  63.  
  64. CMPDPanelSelectTable.cp
  65. CMPDPanelSelectTable.h
  66. A concrete example of a CMPDPanelSelectControl which implements a list interface similar the the System 6 control panel.
  67.  
  68. UMPDialogHandler.cp
  69. UMPDialogHandler.h
  70. The backbone of the whole framework. Handles all of the message passing and determining which panel to load.
  71.  
  72. UResourcePlus.h
  73. A helper class which implements a delayed loading of resources in a stack based class.
  74.  
  75. Future:
  76. All of the source files have extensive comments which should get you started. I'm working on some better documentation of the framework which will be out after I slowly :^) write it. I'm also looking into a version of this which does not need to be in a dialog to function.
  77.  
  78. Version History:
  79. 1.1 (11/15/96)
  80.    • Changed the name of CMPDIndexTab to CMPDAGAIndexTab because of the addition of another Tabbed Dialog control.
  81.    • Fixed a bug introduced in 1.0.1 which affected updating the CMPDAGAIndexTab when switching panels.
  82.    • Added CMPDGrayCouncilTabs based on Trygve Isaacson's Gray Council class.
  83.    • Separated the custom pane types into their own file for easier inclusion into Constructor (MPDialogs Custom Types.rsrc)
  84.    • Enhanced the test application to better show off the different versions of the dialogs.
  85.  
  86. 1.0.1 (09/13/96)
  87.    • Fixed a bug in the CMPDPanelSelectTable which would cause an exception if you clicked outside of the available icons and cause the dialog to be dismissed.
  88.    • Added the ability to click and scroll in the CMPDPanelSelectTable.
  89.    • Improved the visual display when switching between panels
  90.    • Improved ths readme to give a little more info on creating the panel classes.
  91.  
  92. 1.0 (08/31/96)
  93.     • First release
  94.  
  95. Legal Stuff:
  96. Copyright ©1996 Mike Shields. All rights reserved.
  97. I hereby grant users of the Multi-Panel Dialogs framework permission to use it (or any modified version of it) in applications (or any other type of Macintosh software like extensions -- freeware, shareware, commercial, or other) for free, 
  98. subject to the terms that:
  99.     (1)  This agreement is non-exclusive.
  100.  
  101.     (2)  I, Mike Shields, retain the copyright to the original source code.
  102.  
  103. These two items are the only required conditions for use. However, I do have an additional request. Note, however, that this is only a request, and that it is not a required condition for use of this code.
  104.  
  105. • That I be given credit for the Multi-Panel Dialogs framework code in the copyrights or acknowledgements section of your manual or other appropriate documentation.
  106.  
  107. I would like to repeat that this last item is only a request. You are prefectly 
  108. free to choose not to do any or all of them.
  109.  
  110.    This source code is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  111.  
  112. Good, now that's out of the way.
  113.  
  114. Thanks To:
  115. Jerry Shields, Dave DeCoursey, Michael Goodwin, Ali Hariki, Jonathan    Kew, Daniel    Sears, James    Stein Wouter Wessels for their suport and encouragement.
  116.  
  117. Notes:
  118. Please contact me if you have problems (or suggestions!) - Mike Shields <mshields@inconnect.com> and be sure to check out my web page for updates and new releases <http://www.inconnect.com/~mshields/NightOwl.html>
  119.